BCI NET/BCI NET Dec 94.iso/archives/programming/libraries/mui20dev.lha/MUI/Developer/Docs/MUIdev.doc

Text File | 1994-02-11 | 57KB | 1,407 lines

                       MUI - MagicUserInterface

       A system to create and maintain graphical user interfaces

                       Programmer Documentation

                (c) Copyright 1993/94 by Stefan Stuntz

Getting Started
***************

   Note: This documentation does not cover all concepts of MUI
programming in detail. It's important that you also read the
accompanying per class autodocs and have a look at the supplied demo
programs!

Object Oriented Programming
===========================

   The MUI system is based on BOOPSI, the Basic Object Oriented
Programming System for Intuition. Understanding MUI and understanding
this documentation requires at least a little knowledge about the
concepts of object oriented programming, about classes, objects,
methods and attributes. An absolutely sufficient introduction to these
topics can be found in the "Libraries" part of the "ROM Kernel
Reference Manuals" or in several Amiga mail articles.

   When talking about BOOPSI, most people automatically think of BOOPSI
images and BOOPSI gadgets as part of the Amiga operating system.
However, BOOPSI for itself is just a system for object oriented
programming. One could e.g. have object oriented spread sheet software
or object oriented file systems based on BOOPSI, intuition's builtin
classes (gadgetclass, imageclass) are just two from thousands of
possibilities.

   The MUI system also uses BOOPSI only as a base for object oriented
programming. Thus, MUI classes are all subclasses of BOOPSI's rootclass
and have nothing in common with the system supplied gadget or image
classes. Unfortunately, Commodore missed some very important topics
when designing these classes, disabling them for use in automatic
layout systems such as MUI. Anyway, MUI features an interface to
BOOPSI's gadgetclass and allows using already available gadgets (e.g.
the Kick 3.x colorwheel) in MUI applications.

Available Classes
=================

   The MUI system comes with several classes, each of them available as
seperate shared system library. These classes are organized in a tree.
As usual in the OO programming model, objects inherit all methods and
attributes from their true class as well as from all their
superclasses. Here is a quick summary with some short notes what the
classes are used for. More detailed information can be found later in
this document and in the per class autodocs files coming with the
developer archive.

     rootclass               (BOOPSI's base class)
     \--Notify               (implements notification mechanism)
        +--Application       (main class for all applications)
        +--Window            (handles intuition window related topics)
        \--Area              (base class for all GUI elements)
           +--Rectangle      (creates empty rectangles)
           +--Image          (creates images)
           +--Text           (creates some text)
           +--String         (creates a string gadget)
           +--Prop           (creates a proportional gadget)
           +--Gauge          (creates a fule gauge)
           +--Scale          (creates a percentage scale)
           +--Boopsi         (interface to BOOPSI gadgets)
           +--Colorfield     (creates a field with changeable color)
           +--List           (creates a line-oriented list)
           !  +--Floattext   (special list with floating text)
           !  +--Volumelist  (special list with volumes)
           !  +--Scrmodelist (special list with screen modes)
           !  \--Dirlist     (special list with files)
           \--Group          (groups other GUI elements - handles layout)
              +--Virtgroup   (handles virtual groups)
              +--Scrollgroup (handles virtual groups with scrollers)
              +--Scrollbar   (creates a scrollbar)
              +--Listview    (creates a listview)
              +--Radio       (creates radio buttons)
              +--Cycle       (creates cycle gadgets)
              +--Slider      (creates slider gadgets)
              +--Coloradjust (creates some RGB sliders)
              \--Palette     (creates a complete palette gadget)

Application Theory
==================

   A MUI application consists of a (sometimes very) big object tree
(don't mix up with the class tree explained above).  The root of this
tree is always an instance of application class, called application
object. This application object handles the various communication
channels such as user input through windows, ARexx commands or
commodities messages.

   An application object itself would be enough to create non-GUI
programs with just ARexx and commodities capabilities. If you want to
have windows with lots of nice gadgets and other user interface stuff,
you will have to add window objects to your application. Since the
application object is able to to handle any number of children, the
number of windows is not limited.

   Window objects are instances of window class and handle all the
actions related with opening, closing, moving, resizing and refreshing
of intuition windows. However, a window for itself is not of much use
without having any contents to display.  That's why window objects
always need a so called root object.

   With this root object, we finally reach the gadget related classes
of the MUI system. These gadget related classes are all subclasses of
area class, they describe a rectangle region with some class dependant
contents. Many different classes such as strings, buttons, checkmarks
or listviews are available, but the most important subclass of area
class is probably the group class. Instances of this class are able to
handle any number of child objects and control the size and position of
these children with various attributes. Of course these children can
again be group objects with other sets of children.  Since you usually
want your window to contain more than just one object, the root object
of a window will be a group class object in almost all cases.

   Because these first paragraphs are very important to understand how
MUI works, here's a brief summary:

   An application consists of exactly one application object. This
application object may have any number of children, each of them being
a window object. Every window object contains a root object, usually of
type group class. This group object again handles any number of child
objects, either other group objects or some user interface elements
such as strings, sliders or buttons.

   A little diagram might make things more clear:

                                 +-------------+
                                 ! Application !
                                 +-------------+
                                        !
              ... ------+---------------+----------------+
                        !               !                !
                   +--------+       +--------+       +--------+
                   ! Window !       ! Window !       ! Window !
                   +--------+       +--------+       +--------+
                        !               !                !
                    +-------+
                    ! Group !          ...              ...
                    +-------+
                        !
         +------------+-+--------+-----------------+
         !            !          !                 !
     +--------+   +-------+   +------+         +-------+
     ! String !   ! Group !   ! Text !         ! Group !
     +--------+   +-------+   +------+         +-------+
                      !                            !
       ... -----+-----+-----+          +-----------+------- ...
                !           !          !           !
             +------+   +-------+   +------+   +-------+
             ! List !   ! Cycle !   ! List !   ! Group !
             +------+   +-------+   +------+   +-------+
                                                   !
                                             +-----+-----+
                                             !           !
                                         +--------+  +--------+
                                         ! Button !  ! Button !
                                         +--------+  +--------+

   As shown in this tree, only three types of objects are allowed to
have children:

     Application: zero or more children of window class.
          Window: exactly one child of any subclass of area class.
           Group: one or more children of any subclass of area class.

Object Handling
===============

   Since MUI uses BOOPSI as object oriented programming system, objects
could simply be created using intuition.library/NewObject().  However,
`muimaster.library' also features a generation function called

     Object * MUI_NewObjectA(STRPTR class, struct TagItem *taglist);

with the varargs stub
     Object * MUI_NewObject(STRPTR class, Tag tag1, ..., TAG_DONE);

   That's the function you should use when creating objects of public
MUI classes. The parameter `class' specifies the name of the object's
class (e.g. `MUIC_Window', `MUIC_Slider', ...).  If the needed class
isn't already in memory, it is automatically loaded from disk.

   With `taglist', you specify initial create time attributes for your
object. Every attribute from the objects true class or from one of its
super classes is valid here, as long as it's marked with the letter `I'
in the accompanying autodocs documentation.

   To create a string object with a string-kind frame, a maximum length
of 80 and the initial contents "foobar", you would have to use the
following command:

     MyString = MUI_NewObject(MUIC_String,
                    MUIA_Frame          , MUIV_Frame_String,
                    MUIA_String_Contents, "foobar",
                    MUIA_String_MaxLen  , 80,
                    TAG_DONE);

   Once your object is ready, you can start talking to it by setting or
getting one of its attributes or by sending it methods. The standard
BOOPSI functions `SetAttrs()', `GetAttr()' and `DoMethod()' are used
for these purposes:

        char *contents;
        SetAttrs(MyString,MUIA_String_Contents,"look",TAG_DONE);
        GetAttr(MUIA_String_Contents,MyString,&contents);
        printf("Always %s on the bright side of life.",contents);

        DoMethod(mylist,MUIM_List_Remove,42); /* remove entry nr 42 */

   As already mentioned above, all attributes and methods are completely
documented in the autodocs coming with this distribution. These
autodocs follow the usual format, you can parse them with one of the
various tools to create some hypertext online help for your favourite
editor.

   When you're done with an object, you should delete it with a call to

     VOID MUI_DisposeObject(Object *obj);

from `muimaster.library'. After doing so, the object pointer is invalid
and must no longer be used.

   When deleting objects, the parent-child connections mentioned above
play an important role. If you dispose an object with children, not
only the object itself but also all of its children (and their
children, and the children of their children ...) get deleted. Since in
a usual MUI application, the application object is the father of every
window, the window is the father of it's contents and every group is
the father of its sub objects, a single dispose of the application
object will free the entire application.

   Note well: you may *not* delete objects that are currently children
of other objects. Thus, if you have a complete application tree, the
only thing you can delete is the application object itself as this one
has no father. You can, however, add and remove children dynamically.
More information on that topic follows later in this document.

Macros
======

   This chapter is only valid if you use C as your MUI programming
language. Other language interfaces might feature other types of macros
or support functions. Please have a look at the supplied interfaces to
see how they work.

   The tree structure that builds up an application also appears in the
source code of a MUI program. Since adding child objects is always
possible with a special attribute of the parent object, it is common to
create the whole tree with one big function call.

   To help making these calls more clear, the MUI header files contain
several macros that simplify the task of object generation.

   Instead of

     MUI_NewObject(MUIC_Window, ..., TAG_DONE);
     MUI_NewObject(MUIC_String, ..., TAG_DONE);
     MUI_NewObject(MUIC_Slider, ..., TAG_DONE);

you can simply use

     WindowObject, ..., End;
     StringObject, ..., End;
     SliderObject, ..., End;

   Please note that the `xxxObject' macros contain an opening bracket
and thus must always be terminated with an `End' macro that contains
the matching closing bracket.

   Besides these "two way" macros, there are also some complete object
definitions available which all create specific objects with certain
types of attributes. The macro

     SimpleButton("Cancel")

would e.g. generate a complete button object with the correct frame,
background and input capabilities. Though lots of these types of macros
are available and can of course be used directly in your applications,
they are mainly intended as some kind of example. Usually you will need
some more sophisticated generation capabilities with a more specific
set of macros.

   Note: If your application needs lots of objects from a specific type
(e.g. 200 buttons), you can save some memory by turning macros into
functions.

Layout Engine
*************

Overview
========

   One of the most important and powerful features of MUI is its dynamic
layout engine. As opposed to other available user interface tools, the
programmer of a MUI application doesn't have to care about gadget sizes
and positions. MUI handles all necessary calculations automatically,
making every program completely screen, window size and font sensitive
without the need for the slightest programmer interaction.

   From a programmers point of view, all you have to do is to define
some rectangle areas that shall contain the objects you want to see in
your window. Objects of group class are used for this purpose. These
objects are not visible themselves, but instead tell their children
whether they should appear horizontally or vertically (there are more
sophisticated layout possibilities, more on this later).

   For automatic and dynamic layout, it's important that every single
object knows about its minimum and maximum dimensions. Before opening a
window, MUI asks all its gadgets about these values and uses them to
calculate the windows extreme sizes.

   Once the window is opened, layout takes place. Starting with the
current window size, the root object and all its children are placed
depending on the type of their father's group and on some additional
attributes.  The algorithm ensures that objects will never become
smaller as their minimum or larger as their maximum size.

   The important thing with this mechanism is that object placement
depends on window size. This allows very easy implementation of a
sizing gadget: whenever the user resizes a window, MUI simply starts a
new layout process and recalculates object positions and sizes
automatically. No programmer interaction is needed.

Groups
======

   As mentioned above, a programmer specifies a windows outfit by
grouping objects either horizontally or vertically. As a little
example, lets have a look at a simple file requester window:

     +---------------------------------------+
     !                                       !
     !  +------------------------+ +------+  !
     !  ! C                (dir) ! ! dh0: !  !
     !  ! Classes          (dir) ! ! dh1: !  !
     !  ! Devs             (dir) ! ! dh2: !  !
     !  ! Expansion        (dir) ! ! df0: !  !
     !  ! ...                    ! ! df1: !  !
     !  ! Trashcan.info    1.172 ! ! df2: !  !
     !  ! Utilities.info     632 ! ! ram: !  !
     !  ! WBStartup.info     632 ! ! rad: !  !
     !  +------------------------+ +------+  !
     !                                       !
     !  Path: _____________________________  !
     !                                       !
     !  File: _____________________________  !
     !                                       !
     !  +------+                 +--------+  !
     !  ! Okay !                 ! Cancel !  !
     !  +------+                 +--------+  !
     !                                       !
     +---------------------------------------+

   This window consists of two listview objects, two string gadgets and
two buttons. To tell MUI how these objects shall be placed, you need to
define groups around them. Here, the window consists of a vertical group
that contains a horizontal group with both lists as first child, the
path gadget as second child, the file gadget as third child and again a
horizontal group with both buttons as fourth child.

   Using the previously defined macro language, the specification could
look like this (in this example, `VGroup' creates a vertical group and
`HGroup' creates a horizontal group):

     VGroup,
        Child, HGroup,
           Child, FileListview(),
           Child, DeviceListview(),
           End,
        Child, PathGadget(),
        Child, FileGadget(),
        Child, HGroup,
           Child, OkayButton(),
           Child, CancelButton(),
           End,
        End;

   This tiny piece of source is completely enough to define the
contents of a window, all necessary sizes and positions are
automatically calculated by the MUI system.

   To understand how these calculations work, it's important to know
that all basic objects (e.g. strings, buttons, lists) have a fixed
minimum and a maximum size. Group objects calculate their minimum and
maximum sizes from their children, depending whether they are
horizontal or vertical:

   - Horizontal groups

     The minimum width of a horizontal group is the sum of all minimum
     widths of its children.

     The maximum width of a horizontal group is the sum of all maximum
     widths of its children.

     The minimum height of a horizontal group is the biggest minimum
     height of its children.

     The maximum height of a horizontal group is the smallest maximum
     height of its children.

   - Vertical groups

     The minimum height of a vertical group is the sum of all minimum
     heights of its children.

     The maximum height of a vertical group is the sum of all maximum
     heights of its children.

     The minimum width of a vertical group is the biggest minimum width
     of its children.

     The maximum width of a vertical group is the smallest maximum
     width of its children.

   Maybe this algorithm sounds a little complicated, but in fact it is
really straight forward and ensures that objects will neither get
smaller as their minimum nor bigger as their maximum size.

   Before a window is opened, it asks its root object (usually a group
object) to calculate minimum and maximum sizes. These sizes are used as
the windows bounding dimensions, the smallest possible window size will
result in all objects being display in their minimum size.

   Once minimum and maximum sizes are calculated, layout process
starts. The root object is told to place itself in the rectangle
defined by the current window size. This window size is either
specified by the programmer or results from a window resize operation
by the user. When an object is told to layout itself, it simply sets
its position and dimensions to the given rectangle.  In case of a group
object, a more or less complicated algorithm distributes all available
space between its children and tells them to layout too.

   This "more or less complicated algorithm" is responsible for the
object arrangement. Depending on some attributes of the group object
(horizontal or vertical, ...) and on some attributes of the children
(minimum and maximum dimensions, ...), space is distributed and
children are placed.

   A little example makes things more clear. Let's see what happens in
a window that contains nothing but three horizontally grouped
colorfield objects:

     +---------------------------------+
     !                                 !
     !  +-------+ +-------+ +-------+  !
     !  !       ! !       ! !       !  !
     !  ! field ! ! field ! ! field !  !
     !  !   1   ! !   2   ! !   3   !  !
     !  !       ! !       ! !       !  !
     !  +-------+ +-------+ +-------+  !
     !                                 !
     +---------------------------------+

   Colorfield objects have a minimum width and height of one pixel and
no (in fact a very big) maximum width and height. Since we have a
horizontal group, the minmax calculation explained above yields to a
minimum width of three pixels and a minimum height of one pixel for the
windows root object (the horizontal group containing the colorfields).
Maximum dimensions of the group are unlimited. Using these results, MUI
is able to calculate the windows bounding dimensions by adding some
spacing values and window border thicknesses.

   Once min and max dimensions are calculated, the window can be opened
with a programmer or user specified size. This size is the starting
point for the following layout calculations. For our little example,
let's imagine that the current window size is 100 pixels wide and 50
pixels high.

   MUI subtracts the window borders and some window inner spacing and
tells the root object to layout itself into the rectangle left=5,
top=20, width=90, height=74. Since our root object is a horizontal
group in this case, it knows that each colorfield can get the full
height of 74 pixels and that the available width of 90 pixels needs to
be shared by all three fields.  Thus, the resulting fields will all get
a width of 90/3=30 pixels.

   That's the basic way MUI's layout system works. There are a lot more
possibilities to influence layout, you can e.g.  assign different
weights to objects, define some inter object spacing or even make
two-dimensional groups. These sophisticated layout issues are discussed
in the autodocs of group class.

Building An Application
***********************

Creation
========

   Creating all the objects that make up an applications user interface
is usually done with one big `MUI_NewObject()' call. This call returns
a pointer to the application object as its result and contains lots of
other object creation calls as parameter for its tag items. Using the
previously defined macro language, a sample generation call could look
like this:

     app = ApplicationObject,
        MUIA_Application_Title      , "Settings",
        MUIA_Application_Version    , "$VER: Settings 6.16 (20.10.93)",
        MUIA_Application_Copyright  , "©1992/93, Stefan Stuntz",
        MUIA_Application_Author     , "Stefan Stuntz",
        MUIA_Application_Description, "Just a silly demo",
        MUIA_Application_Base       , "SETTINGS",

        SubWindow, window1 = WindowObject,
           MUIA_Window_Title, "Save/use me and start me again!",
           MUIA_Window_ID   , MAKE_ID('S','E','T','T'),

           WindowContents, VGroup,

              Child, ColGroup(2), GroupFrameT("User Identification"),
                 Child, Label2("Name:"  ), Child, str1 = String(0,40),
                 Child, Label2("Street:"), Child, str2 = String(0,40),
                 Child, Label2("City:"  ), Child, str3 = String(0,40),
                 Child, Label1("Passwd:"), Child, str4 = String(0,40),
                 Child, Label1("Sex:"   ), Child, str5 = String(0,40),
                 Child, Label("Age:"),
                 Child, sl  = SliderObject, End,
                 End,

              Child, VSpace(2),

              Child, HGroup,
                 MUIA_Group_SameSize, TRUE,
                 Child, btsave   = KeyButton("Save"  ,'s'),
                 Child, btuse    = KeyButton("Use"   ,'u'),
                 Child, btcancel = KeyButton("Cancel",'>'),
                 End,

              End,
           End,

        SubWindow, window2 = WindowObject,
           MUIA_Window_Title, "Window 2",
           ...,
           ...,
           End,

        SubWindow,
           ...
           End,

        End;

     if (!app) fail(app,"Failed to create Application.");

   This big structure is indeed one single function call that builds a
lot of other objects on the fly. Windows are created as children of the
application object, a windows contents are created as child of the
window and a groups contents are created as children of the group.

   Though many single objects are created, error handling is very easy.
When a parent object encounters a NULL pointer supplied as one of its
children, it will automatically dispose all other supplied children and
fail too. Thus, even errors occuring in a very deep level will cause
the complete application object to fail.  On the other hand, if you
receive a non NULL application pointer, you can be sure that all other
objects have successfully been created.

   Once you're done with your application, a single

     MUI_DisposeObject(app);

is enough to get rid of all previously created objects.

Notificiation
=============

   The central element for controlling a MUI application is the
notification mechanism. To understand how it works, its important to
know that most objects feature lots of attributes that define their
current state. Notification makes it possible to react on changes of
these attributes.

   Attributes are changed either directly by the programmer (with a
call to SetAttrs()) or by the user manipulation some gadgets.  If he
e.g. drags around the knob of a proportional gadget, the
MUIA_Prop_First attribute will continously be updated and reflect the
current position.

   With notification, you could directly use this attribute change to
set the MUIA_List_TopPixel attribute of a list object, building up a
full featured listview:

     DoMethod(sbar, MUIM_Notify, MUIA_Prop_First, MUIV_EveryTime,
              list, 3, MUIM_Set, MUIA_List_TopPixel, MUIV_TriggerValue);

   To make it clear: Every time, the scrollbar object changes its
`MUIA_Prop_First' value, the list object shall change its
`MUIA_List_TopPixel' attribute accordingly. The value 3 in the above
function call identifies the number of the following parameters. Since
you can call any method with any parameters here and MUI needs to save
it somewhere, it's important to set it correctly.

   From now on the list and the scrollbar are connected to each other.
As soon as the proportional gadget is moved, the position of the list
changes accordingly; the programmer doesn't have to care about.

   Notification is mostly used together with either the
`MUIM_Application_ReturnID' or with the `MUIM_CallHook' method. If you
e.g. have a specific hook that should be called whenever the user
presses a button, you could use the following notify method:

     DoMethod(button, MUIM_Notify, MUIA_Button_Pressed, FALSE,
              button, 2, MUIM_CallHook, &ButtonHook);

     /* Whenever the button's pressed attribute is set to FALSE
        (i.e. the user has released the button), the button object
        itself will call ButtonHook. */

   Futher information can be found in the autodocs of notify class.

Dynamic Object Linking
**********************

Overview
========

   Usually, the complete user interface of an application is created
with one single command. This makes error handling very easy and allows
parallel usage of several windows. However, sometimes it makes sense to
create certain windows only when they are actually needed: For example,
if an application supplies many subwindows and would use too much
memory, or if the number and contents of needed windows is not known at
application startup time.

   Therefore MUI supports the option of "late binding".  Using this
mechanism, children can be added and removed after their parent object
already has been created. MUI uses the methods `OM_ADDMEMBER' and
`OM_REMMEMBER' for this purpose:

     DoMethod(parent,OM_ADDMEMBER,child); /* add child object    */
     DoMethod(parent,OM_REMMEMBER,child); /* remove child object */

   Both methods are only supported by MUI's application and group
class; these are the only classes that can manage several children.
Dynamic object linking for window and group class is explained in
detail in the following chapters.

   Note: Objects that do not have parents, be it, because they are not
yet connected using `OM_ADDMEMBER' or because they were disconnected
using `OM_REMMEMBER', it's the programmer's task to delete them by
calling `MUI_DisposeObject()'.  On the other side, objects that still
are children of other objects must not be deleted!

Dynamic Windows
===============

   Let's say an application object is already set up and another (not
yet existing) window has to be added. First, the window object needs to
be created:

     win = WindowObject,
        MUIA_Window_Title, "New Window",
           WindowContents, VGroup,
              Child, ...,
              Child, ...,
              Child, ...,
              End,
           End,
        End;

     if (!win) fail(); /* failure check */

After the window object is created, it can be added to the application
as one of its children:

     DoMethod(app,OM_ADDMEMBER,win);

   Now this window has become a part of the application, just as if it
had been created as a subwindow together with the application object.
It can be opened and closed by setting the according attributes and
will be deleted automatically as soon as the application is ended.

   Usually, however, you'll want to delete this window directly after
usage, because the late binding wouldn't make much sense otherwise.

After closing the window via

     set(win,MUIA_Window_Open,FALSE);

you can remove it by calling

     DoMethod(app,OM_REMMEMBER,win);

   After this you have to delete the window object "by hand", since the
application no longer knows of it:

     MUI_DisposeObject(win);

   This method makes it possible to create subroutines that open their
own window, wait for some imput events und return something.

To illustrate this, here is a short example:

     set(app,MUIA_Application_Sleep,TRUE);  // disable other windows

     win = WindowObject, ...., End;         // create new window

     if (win)                               // ok ?
     {
         DoMethod(app,OM_ADDMEMBER,win);    // add window...
         set(win,MUIA_Window_Open,TRUE);    // and open it

         while (running)
         {
             switch (DoMethod(app,MUIM_Application_Input,&sigs))
             {
                 ... // Extra Input loop. For this window only.
                 ... // Note: The special value
                 ... // MUIV_Application_ReturnID_Quit should be recognized
                 ... // as well
             }
         }

         set(win,MUIA_Window_Open,FALSE);   // Close window

         DoMethod(app,OM_REMMEMBER,win);    // remove

         MUI_DisposeObject(win);            // and kill it
     }

     set(app,MUIA_Application_Sleep,FALSE); // wake up the application

Dynamic Groups
==============

   In the same way you can add windows to an application after its
creation, you can add elements to already existing group objects. This
may be useful if a group contains many similar children or if the
number of children is not known in the beginning.

   You can add new elements to groups or delete them again, but the
window that contains this group must not be open!

A small example:

         app = ApplicationObject,
             ...,
             SubWindow, win = WindowObject,
                 WindowContents, VGroup,
                     ...,
                     grp = VGroup,
                 End,
                 ...,
             End,
         End,
     End;

     /* The group 'grp' has been created without any children. */
     /* The window must not be opened now!                     */

     for (i=0; i<NumPlayers; i++)
     {
        Object *name = StringObject, MUIA_String_MaxLen, 30, End;
        if (name)
           DoMethod(grp,OM_ADDMEMBER,name); // add gadget to group.
        else
           fail();
     }

     /* After we have at least one element in the group 'grp', */
     /* the window can be opened...                            */

   Of course you may (if the window is closed) remove elements from
groups. Please note that window objects containing empty groups must
not be opened.

Custom Classes
**************

Introduction
============

   MUI features a lot of builtin classes that already allow creation of
powerful applications. However, a generic GUI system will never be able
to satisfy all the requirements of all kinds of programs. A sound
editor would e.g. need a class to display and edit sound data, a paint
program would need a drawing area and a chess game would need a
chess-board class.

   Prior to MUI V2.0, programmers were stuck with the builtin classes.
Except of the (sometimes problematic) BOOPSI interface, there was no
way to include custom gadgets in a MUI window. This big disadvantage
has finally disappeared, with MUI 2.0 it's posssible to write and use
private classes just like one of the builtins.

   Beneath the BOOPSI gadget interface, private classes are the only
way to have custom gadgets in a MUI window. Drawing into windows
directly from the applications task is illegal and will surely lead
into lots of problems!

   Note: Since this manual doesn't repeat the RKMs BOOPSI section, you
should be familiar with the BOOPSI mechanisms of dispatchers, methods,
attributes, instance data structures, etc. before going on.

Overview
========

   Building a class is rather simple. All you have to do is to write a
class dispatcher function, setup a hook structure, call MUI_GetClass()
to find the pointer to your superclass and use
intuition.library/MakeClass() to create the class. If you already wrote
BOOPSI classes, you should know whats going on here.

   Objects from custom classes are created using intuition.library /
NewObject(), not muimaster.library / MUI_NewObject(). Nevertheless, you
can use these objects like every other MUI objects, e.g. as children of
groups, in virtual groups or wherever you like.

   All classes you create have to be subclasses of MUI's area class,
most of them will probably be direct subclasses but you can also have
subclasses of list class or even subclasses of your own classes if you
want. Here's an example of how a custom class could be generated:

        /* Get a pointer to the superclass. MUI will lock this */
        /* and prevent it from being flushed during you hold   */
        /* the pointer. When you're done, you have to call     */
        /* MUI_FreeClass() to release this lock.               */

        if (!(SuperClass=MUI_GetClass(MUIC_Area)))
           fail("Superclass for the new class not found.");

        /* Create the new class with the boopsi function call. */
        /* You will need the sizeof your classes instance data */
        /* here.                                               */

        if (!(MyClass = MakeClass(NULL,NULL,SuperClass,sizeof(struct MyData),0)))
        {
           MUI_FreeClass(SuperClass);
           fail("Failed to create class.");
        }

        /* Set the dispatcher for the new class. */

        MyClass->cl_Dispatcher.h_Entry    = (APTR)MyDispatcher;
        MyClass->cl_Dispatcher.h_SubEntry = NULL;
        MyClass->cl_Dispatcher.h_Data     = NULL;

        ...
        ...

        app = ApplicationObject,
           ...,

           SubWindow, window = WindowObject,
              ...
              WindowContents, VGroup,

                 Child, MyObj = NewObject(MyClass,NULL,
                    TextFrame,
                    MUIA_Background, MUII_BACKGROUND,
                    TAG_DONE),

                 End,

              End,
           End;

        ...
        ...

        /* Shutdown. When the application is disposed,
        /* MUI also deletes MyObj. */

        MUI_DisposeObject(app);     // dispose all objects.
        FreeClass(MyClass);         // free our private class.
        MUI_FreeClass(SuperClass);  // release super class pointer.

   You're dispatcher will look like a traditional BOOPSI dispatcher:

     SAVEDS ASM ULONG MyDispatcher(
        REG(a0) struct IClass *cl,
        REG(a2) Object *obj,
        REG(a1) Msg msg)
     {
        switch (msg->MethodID)
        {
           case OM_NEW        : return(mNew      (cl,obj,(APTR)msg));
           case OM_DISPOSE    : return(mDispose  (cl,obj,(APTR)msg));
           case MUIM_AskMinMax: return(mAskMinMax(cl,obj,(APTR)msg));
           case MUIM_Draw     : return(mDraw     (cl,obj,(APTR)msg));
           ...
        }

        return(DoSuperMethodA(cl,obj,msg));
     }

   What methods are available and need to be supported is discussed in
the following chapter.

   Note: Your dispatcher will also receive some undocumented methods.
It's not a wise choice to make any assumptions here, the only thing you
should do is pass them to your superclass immediately!

Methods
=======

   The MUI system talks to its classes with a specific set of methods.
Some of these methods need to be implemented by all MUI classes but
most of them are optional.  This chapter gives a quick overview about
the methods your class might receive.  All methods are discussed more
detailed in the following sections.

   As usual with BOOPSI objects, you will get an OM_NEW whenever a new
object of your class shall be created. Since with MUI, the deepest
nested objects are always created first, your object won't know anything
about its display environment during OM_NEW.

   After all objects are created, MUI finds out about the display
environment (screen, drawinfo structure, fonts, etc.) and sends you a
MUIM_Setup method with this information. You can calculate some
internal data here that depends on the display enviroment (e.g. the
line height in an editor class). Note that you still don't have a
intuition window at this point.

   The next method your class receives is called MUIM_AskMinMax. MUI
wants to find out about your minimum, maximum and default sizes to
prepare its window size calculation and layout algorithms. Since you
already know about display environment, calculating these values should
be easy at this point.

   After asking all objects about their dimensions and adding the
results depending on the type of group your object resides in, MUI is
able to open the window. Once it is open, your object will receive a
MUIM_Show method telling you that you are about to be added to the
window.  MUIM_Show is mainly intended for use by intuition like
gadgets, they will do an AddGadget() here (and a RemGadget() during
MUIM_Hide). Usually, you won't need to implement these methods.

   Since your class still didn't draw anything, its time for a
MUIM_Draw method now. MUI sends this method whenever it feels that you
should draw yourself.  This happens of course after a window has been
opened but also when you reside in a simple refresh window and need to
be refreshed. MUIM_Draw is the only place where you are actually
allowed to draw something!

   When the window is resized, MUI sends a MUIM_Hide (allowing some
RemGadget() for intuition like gadgets), calculates new positions and
sizes and sends a MUIM_Show and a MUIM_Draw again. However, if you
correctly implement MUIM_Draw, you don't need to care about this in
almost all cases.

   When your window is about to be closed (either because your
application no longer needs it or because the user iconified your
program or changed the preferences settings), you will receive a
MUIM_Cleanup. This allows you to free some display environment
dependant things you allocated during MUIM_Setup.

   The last thing your object will get is of course a OM_DISPOSE after
it has hopefully done all the things you wanted it to do.

   To sum it up again, look at the diagram below. Things between
brackets might be called zero or more times for the same object.

     OM_NEW; /* you dont know anything about display environment here */
     {
        MUIM_Setup;      /* information about display, still no window */
        MUIM_AskMinMax;  /* tell me your min/max dimensions */
        [ window is opened here ]
        {
           MUIM_Show;    /* add yourself to the window, don't yet draw */
           {
              MUIM_Draw;     /* draw yourself */
           }
           MUIM_Hide;    /* remove yourself from the window */
        }
        [ window is closed here ]
        MUIM_Cleanup;    /* free any display dependant data */
     }
     OM_DISPOSE; /* kill yourself completely */

   As you probably noticed, most methods are implemented as
constructor/destructor pairs: OM_NEW & OM_DISPOSE, MUIM_Setup &
MUIM_Cleanup, MUIM_Show & MUIM_Hide. For every constuctor call, you
will receive exactly one destructor call. Usually, you will allocate
some resources during OM_NEW, MUIM_Setup or MUIM_Show and free these
resources during OM_DISPOSE, MUIM_Cleanup or MUIM_Hide respectively.

   The three levels of constructor/destructor pairs feature different
amount of available information about the display environment.

   - OM_NEW (destructor OM_DISPOSE)

     No information at all. All you can do is parse the initial
     attribute list and store its contents in the instance data
     structure of your object.

   - MUIM_Setup (destructor MUIM_Cleanup)

     MUI has figured out what screen and font to use. You can
     allocate/calculate things that depend on this information.

   - MUIM_Show (destructor MUIM_Hide)

     MUI has finally opened an intuition window at this point. You are
     able to allocate resources depending on a window context here.

   You can rely on the fact that you receive OM_NEW before MUIM_Setup
(of course, otherwise you wouldn't have a valid object pointer) and
MUIM_Setup before MUIM_Show. But always keep in mind that you might get
multiple MUIM_Show / MUIM_Hide pairs or MUIM_Setup / MUIM_Cleanup pairs
or that you could receive a MUIM_Setup / MUIM_Cleanup pair without some
MUIM_Show / MUIM_Hide between.

OM_NEW & OM_DISPOSE
===================

   Implementing these methods for MUI objects is mainly identical to
traditional BOOPSI objects. The only thing important to remember is
that MUI objects have really no idea about display environment or other
configuration issues when receiving OM_NEW. The ops_GInfo member of the
opSet parameter structure is always unused.  Typical new/dispose
methods consist of some tag list parsing and instance data
initialisation.


     static ULONG mNew(struct IClass *cl,Object *obj,struct opSet *msg)
     {
        struct INST_DATA *data;

        if (!(obj = (Object *)DoSuperMethodA(cl,obj,msg)))
           return(0);

        data = INST_DATA(cl,obj);

        data->min = GetTagData(MYATTR_Min,  0,msg->ops_AttrList);
        data->max = GetTagData(MYATTR_Max,100,msg->ops_AttrList);
        data->lvl = GetTagData(MYATTR_Lvl, 50,msg->ops_AttrList);

        data->count  = data->max - data->min + 1;
        data->buffer = NULL;

        if (data->count > 0)
        {
           if (data->buffer = AllocVec(data->count * 4))
           {
              return((ULONG)obj);
           }
        }

        /* invoke OM_DISPOSE on *our* class! */
        CoerceMethod(cl,obj,OM_DISPOSE);
        return(0);
     }


     static ULONG mDispose(struct IClass *cl,Object *obj,Msg msg)
     {
        struct Data *data = INST_DATA(cl,obj);

        if (data->buffer) FreeVec(data->buffer);

        return(DoSuperMethodA(cl,obj));
     }

MUIM_Setup & MUIM_Cleanup
=========================

   Since your object doesn't know anything about display environment
after it is created with OM_NEW, MUI will send you an MUIM_Setup when
it is about to open a window containing your object.

   The first thing you have to do is to pass MUIM_Setup to your super
class an return FALSE on failure. After this, you can calculate some
internal data or allocate some display buffers. Return TRUE if
everything went ok or FALSE when you discovered any errors. In this
case, MUI will send a MUIM_Cleanup to all objects that already received
a MUIM_Setup (excluding the current one!) and fail to open the window.
Typical setup/cleanup pairs could look like this:


     static ULONG mSetup(struct IClass *cl,Object *obj,Msg msg)
     {
        struct Data *data = INST_DATA(cl,obj);

        if (!(DoSuperMethodA(cl,obj,msg)))
           return(FALSE);

        data->lineheight = _font(obj)->tf_YSize;

        if (!(data->linebuf = AllocVec(data->count*data->lineheight)))
           return(FALSE);

        MUI_RequestIDCMP(obj,IDCMP_RAWKEY|IDCMP_MOUSEBUTTONS|IDCMP_INACTIVEWINDOW);

        return(TRUE);
     }


     static ULONG mCleanup(struct IClass *cl,Object *obj,Msg msg)
     {
        struct Data *data = INST_DATA(cl,obj);

        FreeVec(data->linebuf);

        MUI_RejectIDCMP(obj,IDCMP_RAWKEY|IDCMP_MOUSEBUTTONS|IDCMP_INACTIVEWINDOW);

        return(DoSuperMethodA(cl,obj));
     }

MUIM_AskMinMax
==============

   With MUIM_AskMinMax, MUI wants to find out about the minimum,
maximum and default sizes of your object. These values are needed for
the correct layout, depending on the type of group that contains your
object.


     static ULONG mAskMinMax(
        struct IClass *cl,
        Object *obj,
        struct MUIP_AskMinMax *msg)
     {
        /*
        ** let our superclass first fill in what it thinks about sizes.
        ** this will e.g. add the size of frame and inner spacing.
        */

        DoSuperMethodA(cl,obj,msg);

        /*
        ** now add the values specific to our object. note that we
        ** indeed need to *add* these values, not just set them!
        */

        /* x-size depending on objects font */
        msg->MinMaxInfo->MinWidth  += _font(obj)->tf_XSize * 10;
        msg->MinMaxInfo->DefWidth  += _font(obj)->tf_XSize * 20;
        msg->MinMaxInfo->MaxWidth  += MAXMAX; /* unlimited */

        /* fixed y-size */
        msg->MinMaxInfo->MinHeight += _font(obj)->tf_YSize;
        msg->MinMaxInfo->DefHeight += _font(obj)->tf_YSize;
        msg->MinMaxInfo->MaxHeight += _font(obj)->tf_YSize;

        return(0);
     }

MUIM_Show & MUIM_Hide
=====================

   Once the window is opened, your object will receive a MUIM_Show. If
you have some window/rastport environment dependant things to do,
MUIM_Show is the correct place. Intuition like gadgets would for
example do an AddGadget() here.

   Note that you should *not* render during MUIM_Show. Usually, MUI
classes won't need to implement this method.

MUIM_Draw
=========

   Whenever MUI feels that your object should render itself, it sends
you a MUIM_Draw method. This happens e.g. when a window is openend for
the first time, after a window was resized or when a simple refresh
window needs to be refreshed. In the latter case, MUI already set up a
clip region to restrict rendering to the necessary areas.

   Together with MUIM_Draw comes a flag value that indicates which
parts of the object are to be redrawn. The only interesting bits in
this flag value are MADF_DRAWOBJECT and MADF_UPDATE. When
MADF_DRAWOBJECT is set, MUI wants you to do a complete redraw of your
object. MADF_UPDATE is not used by the MUI system itself but is
reserved for your private requirements width the MUI_Redraw() function
call. See the example programs coming with the MUI distribution for
details.

   Information about rendering environment (screen, window, rastport,
pens, etc.) is saved in a structure called MUI_RenderInfo. Every
objects render info structure is accessable with the muiRenderInfo(obj)
macro. Parts of this structure are valid between MUIM_Setup and
MUIM_Cleanup, other parts like window and rastport pointer are valid
between MUIM_Show and MUIM_Hide. Please have a look at the supplied
compiler headers for more detailed information about the MUI_RenderInfo
structure.

   Note: MUIM_Draw is the only place where you are allowed to render!

MUIM_HandleInput
================

   Compared with BOOPSI, MUI uses a different input handling scheme. Not
only the "active" object but instead all objects may receive input
events at the same time. Since sending input events to every object in
a window would be an incredible overhead, you have to specify what
messages you really need. MUI offers the library calls
MUI_RequestIDCMP() and MUI_RejectIDCMP() for this purpose. Whenever an
arriving input event matches your request, your object will receive a
MUIM_HandleInput method.

   You can call MUI_RequestIDCMP() and MUI_RejectIDCMP() at every time.
Performance affecting critical events like INTUITICKS and MOUSEMOVEs
should only be requested when you really need them. The "Class3" for
example requests MOUSEBUTTONS and RAWKEY during MUIM_Setup. The critical
MOUSEMOVES are only requested when a button was pressed and immediately
rejected after it was released again.

   Beneath the struct IntuiMessage, MUIM_HandleInput receives a longword
describing a MUIKEY as second parameter. If this is set to some other
value as MUIKEY_NONE, your object is the actve object and the input
event translated to a user configured keyboard action.

   MUI will *not* translate input events to your objects coordinates.
This is up to you. A typical input implementation could look like this:


     static ULONG mHandleInput(
        struct IClass *cl,
        Object *obj,
        struct MUIP_HandleInput *msg)
     {
        #define _between(a,x,b) ((x)>=(a) && (x)<=(b))
        #define _isinobject(x,y) (_between(_mleft(obj),(x),_mright (obj))\
                               && _between(_mtop(obj) ,(y),_mbottom(obj)))

        struct Data *data = INST_DATA(cl,obj);

        if (msg->muikey)
        {
           switch (msg->muikey)
           {
              case MUIKEY_LEFT :
                 data->sx=-1;
                 MUI_Redraw(obj,MADF_DRAWUPDATE);
                 break;
              case MUIKEY_RIGHT:
                 data->sx= 1;
                 MUI_Redraw(obj,MADF_DRAWUPDATE);
                 break;
              case MUIKEY_UP   :
                 data->sy=-1;
                 MUI_Redraw(obj,MADF_DRAWUPDATE);
                 break;
              case MUIKEY_DOWN :
                 data->sy= 1;
                 MUI_Redraw(obj,MADF_DRAWUPDATE);
                 break;
           }
        }

        if (msg->imsg)
        {
           switch (msg->imsg->Class)
           {
              case IDCMP_MOUSEBUTTONS:
              {
                 if (msg->imsg->Code==SELECTDOWN)
                 {
                    if (_isinobject(msg->imsg->MouseX,msg->imsg->MouseY))
                    {
                       data->x = msg->imsg->MouseX;
                       data->y = msg->imsg->MouseY;
                       MUI_Redraw(obj,MADF_DRAWUPDATE);
                       MUI_RequestIDCMP(obj,IDCMP_MOUSEMOVE);
                    }
                 }
                 else
                    MUI_RejectIDCMP(obj,IDCMP_MOUSEMOVE);
              }
              break;

              case IDCMP_MOUSEMOVE:
              {
                 if (_isinobject(msg->imsg->MouseX,msg->imsg->MouseY))
                 {
                    data->x = msg->imsg->MouseX;
                    data->y = msg->imsg->MouseY;
                    MUI_Redraw(obj,MADF_DRAWUPDATE);
                 }
              }
              break;
           }
        }

        /* passing MUIM_HandleInput to the super class is only necessary
           if you rely on area class input handling (MUIA_InputMode). */

        return(0);
     }

OM_SETGET
=========

   Implementing OM_SET and OM_GET is similar to oldstyle BOOPSI gadgets.
The only important thing to know about is that you should *not* render
in a OM_SET (e.g. as a result of an attribute change). Instead, call
MUI_Redraw() with a MADF_DRAWOBJECT or a MADF_UPDATE flag, MUI will
then call your objects Draw method.


     static ULONG mSet(struct IClass *cl,Object *obj,Msg msg)
     {
        struct MyData *data = INST_DATA(cl,obj);
        struct TagItem *tags,*tag;

        for (tags=((struct opSet *)msg)->ops_AttrList;tag=NextTagItem(&tags);)
        {
           switch (tag->ti_Tag)
           {
              case MYATTR_PEN:
                 data->pen = tag->ti_Data;         /* set the new value */
                 MUI_Redraw(obj,MADF_DRAWOBJECT);  /* complete redraw */
                 break;

              case MYATTR_LEVEL:
                 data->level = tag->ti_Data;       /* set the new value */
                 MUI_Redraw(obj,MADF_DRAWUPDATE);  /* only update ourselves */
                 break;
           }
        }

        return(DoSuperMethodA(cl,obj,msg));
     }

CSC_DISTRIBUTE
==============

   Usually, you will use custom classes only for your own applications.
In this case, you won't need to care about the tag values used for your
private attributes and methods. The only thing you should consider is
that all standard MUI classes use values betwenn 0x80420000 and
0x8042ffff for their tags. To avoid conflicts, all you have to do is
make your tags start with anything but 0x8042.

   However, if you start distributing your classes to make other people
benefit from your work and help them in writing better MUI applications,
things get a bit more complicated. MUI will get confused if two or more
classes start using some equal tag values. To avoid these problems, I
suggest to use your MUI serial number together with the TAG_USER bit as
upper word for your tag items. Thus, if your serial number is e.g. 123,
all your tag items would look like

     #define MUIA_Myclass_Foobar     (TAG_USER | (123<<16) | 0x0000)
     #define MUIA_Myclass_Barfoo     (TAG_USER | (123<<16) | 0x0001)
     #define MUIA_Myclass_Deadbeaf   (TAG_USER | (123<<16) | 0x0002)
     #define MUIM_Myclass_Doit       (TAG_USER | (123<<16) | 0x0003)
     #define MUIM_Myclass_Doit2      (TAG_USER | (123<<16) | 0x0004)

     #define MUIA_Myotherclass_Attr1 (TAG_USER | (123<<16) | 0x0010)
     #define MUIA_Myotherclass_Attr2 (TAG_USER | (123<<16) | 0x0011)
     #define MUIA_Myotherclass_Attr3 (TAG_USER | (123<<16) | 0x0012)
     #define MUIA_Myotherclass_Attr4 (TAG_USER | (123<<16) | 0x0013)

   If you aren't registered and don't yet have a serial number, no
problem... just register *now*! ;-)

Style Guide
***********

Overview
========

   Note: These topics aren't discussed here just for fun. You will
annoy lots of users if you don't pay attention to them!

   - File Requester

     Even if MUI features a file list and a volume list object and
     makes building a private file requester very easy, you should
     always provide a possibility to pop up a standard asl requester
     for this purpose. Just add a little popup button right beneath
     your file string gadget and everything will be fine. MUI offers a
     file-popup object exactly for this purpose.  Note well: Many users
     (including myself) move programs with non-standard file requesters
     into the trashcan immediately.

   - Window Size

     With MUI, it's very easy to have lots of gadgets within a single
     window.  Since you as a programmer usually have a more powerful
     system with higher graphic resolutions as most of your users,
     windows tend to become too big. You should always make sure that
     everything you design fits on a standard 640x256 screen with a
     topaz/8 font. Otherwise, MUI will try to use very small fonts or
     virtual groups to make your window fit, making your application
     look and feel bad.

   - Keyboard Control

     Even if you're a "mouse-only" user, add keyboard cycle chains and
     gadget shortcuts to your application. It's very few work for you
     and helps lots of users.

   - Background

     MUI allows the user to adjust lots of different backgrounds for
     objects.  Even if you don't use this feature, you should always
     test your program with a fancy background pattern configuration
     and check whether all your buttons really have button backgrounds,
     all your framed texts really have text backgrounds, etc.

   - and last...

     Don't forget the traditional Amiga style guide!